<?xml version="1.0" encoding="UTF-8"?>
<html><head><title>Modes of Operation</title></head><body bgcolor="ffffff"><table cellspacing="10"><tr><td align="center"><a href="http://www.beanshell.org/"><img src="../images/homebutton.gif"/><br/>Home</a></td><td><a href="classpath.html#Class_Loading_and_Class_Path_Management"><img src="../images/backbutton.gif"/><br/>Back
			</a></td><td align="center"><a href="contents.html"><img src="../images/upbutton.gif"/><br/>Contents</a></td><td align="center"><a href="embeddedmode.html#Embedding_BeanShell_in_Your_Application"><img src="../images/forwardbutton.gif"/><br/>Next
			</a></td></tr></table><h1>Modes of Operation</h1>


There are currently five basic modes of operation for running BeanShell:

<ul>
<li>Standalone scripts</li>
<li>Embedded in your application</li>
<li>Remote server mode</li>
<li>Servlet mode</li>
<li>Applet mode</li>
</ul>

We'll outline these in this and the coming sections.
<p CLEAR="ALL"/>

BeanShell is also integrated into a number of other tools and development
environments including the Emacs JDE and the NetBeans/Forte for Java IDE.
Please see the web site for articles and information about using BeanShell
within these third party tools.

<h2><a name="Standalone">Standalone</a></h2>

<img src="../images/scriptmode.gif"/>
<br CLEAR="ALL"/>

You can use BeanShell to run scripts from the command line or enter
statements interactively by starting the bsh.Interpreter class.
(See "Quickstart" for instructions on adding BeanShell to your classpath.)
<p CLEAR="ALL"/>

<p/><center><table border="1" cellpadding="5" width="100%"><tr><td bgcolor="#dfdfdc"><pre>
 java bsh.Interpreter [ filename ] [ arg ] [ ... ]  // Run a script file
</pre></td></tr></table></center><p/>

There are a few options which can be passed to the Interpreter using Java
system properties:

<ul>
<li><strong>outfile</strong> - Send all output to the specified file by 
redirecting System.out and System.err</li>

<li><strong>debug</strong> - Turn on debugging output by setting to
true.  <em>Note: this mode
is very verbose and unstructured.  It is not intended for general
use.</em></li>

<li><strong>trace</strong> - Setting trace to true turns on method tracing.  
This mode prints each line before it is executed.  <em>Note that this currently 
prints only top level lines as they are parsed and executed by the 
interpreter.  Trace skips over method executions (including bsh commands) 
etc.  This mode is incomplete.  It should be considered experimental.</em>
</li>
</ul>

<h2><a name="Remote">Remote</a></h2>

The bsh.Remote launcher is the equivalent of bsh.Interpreter, but runs
the specified file in a remote BeanShell engine.  The remote engine may
be a servlet mode BeanShell engine (BshServlet) or a native server mode 
remote BeanShell instance (embedded interpreter).
<p CLEAR="ALL"/>

bsh.Remote accepts a URL and filename as arguments:

<p/><center><table border="1" cellpadding="5" width="100%"><tr><td bgcolor="#dfdfdc"><pre>
// servlet mode URL
java bsh.Remote http://localhost/bshservlet/eval test1.bsh

// remote server mode URL
java bsh.Remote bsh://localhost:1234/ test1.bsh
</pre></td></tr></table></center><p/>

An HTTP URL may be specified that points to an instance of BshServlet
(See "Servlet Mode" for details).  Or a native "bsh:" URL may be specified,
pointing to an instance of the BeanShell interpreter running in remote
server mode.

<em>
At the time of this writing bsh: style URLs for accessing native remote
server mode instances are not implemented.
</em>
<p CLEAR="ALL"/>

In either case, bsh.Remote sends the script to the remote engine for
evaluation.  If Remote can parse the retun value of the script as an integer 
it will return the value as the exit status to the command line.  

<h2><a name="Interactive_Use">Interactive Use</a></h2>

One of the most popular uses for BeanShell is, of course, as a "shell" for
interactive experimentation and debugging.  BeanShell can be run in a GUI 
desktop mode that offers a number conveniences like command line history,
cut &amp; paste, and tools for interactive use such as a simple classbrowser.  
We'll talk about the GUI in "The BeanShell Desktop" later.  

<p/><center><table cellpadding="5" border="1" width="100%"><tr><td><strong>Tip:</strong><br CLEAR="ALL"/>
The BeanShell GUI is comprised mostly of a set of BeanShell scripts supplied 
in the JAR file and launched by the BeanShell desktop() command.
</td></tr></table></center><p/>

However BeanShell can also be run interactively in plain text on the command 
line.  

<p/><center><table border="1" cellpadding="5" width="100%"><tr><td bgcolor="#dfdfdc"><pre>
 java bsh.Interpreter   // Run interactively on the command line
</pre></td></tr></table></center><p/>

This is useful for quick "one liners"; however it does not offer 
creature comforts such as command line history and editing.  We should note
that some shells, such as the Windows environment, do command line history 
and editing automatically - providing these features for BeanShell.
<p CLEAR="ALL"/>

<p/><center><table cellpadding="5" border="1" width="100%"><tr><td><strong>Tip:</strong><br CLEAR="ALL"/>
You can exit from an interactive shell by typing Control-D.
</td></tr></table></center><p/>

The return statement is ignored in interactive mode (it does not exit the 
shell).
<p CLEAR="ALL"/>

<h2><a name="The_.bshrc_Init_File">The .bshrc Init File</a></h2>

When run interactively, BeanShell looks for a startup file called ".bshrc"
in the user's home directory.  If the file is found it is sourced into the
interactive shell.  You can use this to perform setup for your interactive
use.  For example, to add additional default imports or to toggle on the
show() command if you prefer that.
<p CLEAR="ALL"/>

The location of the .bshrc file is determined by the Java system property
"user.home", which has different locations under different operating systems.
The following table lists common locations:

<h3>.bshrc File Location:</h3>

<table border="1" cellpadding="5">
<tr><td>Unix</td><td>$HOME/.bshrc</td></tr>

<tr><td>
Win95/98 single user
</td><td>
C:\Windows\.bshrc 
</td></tr>

<tr><td>
Win98 Multiuser
</td><td>
C:\Windows\Profiles\&lt;username&gt;\.bshrc
</td></tr>

<tr><td>
NT/2K
</td><td> 
C:\Winnt\Profiles\&lt;username&gt;\.bshrc
</td></tr>

</table>

<table cellspacing="10"><tr><td align="center"><a href="http://www.beanshell.org/"><img src="../images/homebutton.gif"/><br/>Home</a></td><td><a href="classpath.html#Class_Loading_and_Class_Path_Management"><img src="../images/backbutton.gif"/><br/>Back
			</a></td><td align="center"><a href="contents.html"><img src="../images/upbutton.gif"/><br/>Contents</a></td><td align="center"><a href="embeddedmode.html#Embedding_BeanShell_in_Your_Application"><img src="../images/forwardbutton.gif"/><br/>Next
			</a></td></tr></table></body></html>